home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Shareware Grab Bag
/
Shareware Grab Bag.iso
/
007
/
rascal.arc
/
RASCAL.DOC
< prev
next >
Wrap
Text File
|
1980-01-01
|
29KB
|
901 lines
November 1983
This document tells how to use the Rascal BASIC preprocessor
program, RASCAL.EXE, and tells how to write programs for the IBM
PC in the Rascal language. This manual assumes you are familiar
with MS DOS and Microsoft BASIC.
RASCAL USER'S MANUAL RASCAL USER'S MANUAL
Manual version: 1.05
Software version: 1.05
Marty Franz
525 W. Walnut St., Kalamazoo, MI 49007
(616) 344-1821
(C) Copyright 1983 Marty Franz - All rights reserved
111483105 Rascal Preprocessor User's Manual
INTRODUCTION INTRODUCTION
RASCAL.EXE is a preprocessor program for Microsoft BASIC on
the IBM PC. It takes a program containing special Rascal
statements and translates it into a program containing BASIC
statements. Using Rascal helps you write more concise, better
structured BASIC programs, because the preprocessor lets you take
advantage of these features:
- you now have the ability to write free-form, indented
statements without line numbers.
- you can now include statements from many separate files
into a single BASIC program. This lets you write and
maintain your programs in small modules.
- you can organize your subroutines into procedures, each
with its own alphanumeric name.
- you can use structured programming statements similar to
those found in programming languages like Pascal and C.
Before using RASCAL.EXE, please take the time to read these
instructions carefully. When using it, bear in mind that this is
version 1.05 of the program, and there may be bugs in it. If
there is, or you have suggestions on improving Rascal, please
contact me:
Marty Franz
525 W. Walnut St.
Kalamazoo, MI 49007
(616) 344-1821
One more thing: the program, and this manual, are copyrighted
materials. They may be freely distributed only for private,
noncommercial use. Please read the copyright notice on your
diskette.
A SAMPLE PROGRAM A SAMPLE PROGRAM
Before describing Rascal in too much detail, let's first look
at a typical program. This will help you understand what
RASCAL.EXE does. The file LC.RAS on the Rascal diskette is a
good example. It asks for the name of a text file and counts the
number of lines in it. You can make a listing of LC.RAS on your
printer with the PRINT program supplied on the diskette:
A>llist lc.ras
(See the LLIST program instructions for more information on the
LLIST program.)
Page 2 111483105 Rascal Preprocessor User's Manual
Your listing of LC.RAS should look like this:
'Sample Rascal program to count the lines in an ASCII file.
PROCEDURE MAIN
ON ERROR GOTO CHECK.FOR.EOF
INPUT "File Name"; FILE.NAME$
OPEN FILE.NAME$ FOR INPUT AS #1
LINE.COUNT = 0 : DONE.SW = 0
REPEAT
LINE INPUT #1, L$
LINE.COUNT = LINE.COUNT+1
UNTIL DONE.SW = 1
PRINT "There are";LINE.COUNT-1;"lines in ";FILE.NAME$
ENDPROC
CHECK.FOR.EOF|
ERROR.CODE = ERR : ERROR.LINE = ERL
IF ERROR.CODE = 62
DONE.SW = 1
RESUME NEXT
ELSE
PRINT "BASIC error ";ERROR.CODE;"at";ERROR.LINE
STOP 'Immediately halt program
ENDIF
END
This file (called a source file in this manual) was created ______ ____
using the RED.EXE program. For more information about RED, see
the separate file about it on the diskette. Don't worry at this
point about the details of each statement in the program; we'll
be covering them shortly. For now, notice only that a Rascal
program, unlike a BASIC program, has line-number-free, neatly
indented statements, and empty lines to separate blocks of
statements. In fact, it resembles those Pascal programs you've
seen in magazines more than BASIC. Because the program looks
more structured than BASIC, it ought to be easier to understand
and maintain.
Unfortunately, this program cannot be executed directly by
BASIC. We need to convert this program into one with everyday
BASIC statements in it before we can run it. This is what
RASCAL.EXE does. To build a BASIC program out of LC.RAS, we
enter:
A>rascal lc.ras lc.bas
and these messages appear:
Page 3 111483105 Rascal Preprocessor User's Manual
Rascal BASIC preprocessor, version 1.05
(C) Copyright 1983 Marty Franz
60KB to spare
Done with pass 2, 0 error(s) found.
22 lines processed, 147 lines/minute.
A>
After the RASCAL.EXE is done, if we then type the output
file, LC.BAS, we see:
A>type lc.bas
10 'LC.RAS 10-14-83 5:48a 22 lines
20 GOSUB 50
30 END
40 'Sample Rascal program to count the lines in an ASCII
file
50 'PROCEDURE MAIN
60 ON ERROR GOTO 150
70 INPUT "File Name"; FILE.NAME$
80 OPEN FILE.NAME$ FOR INPUT AS #1
90 LINE.COUNT = 0 : DONE.SW = 0
100 LINE INPUT #1, L$
110 LINE.COUNT = LINE.COUNT+1
120 IF NOT(DONE.SW = 1) THEN 100
130 PRINT "There are";LINE.COUNT-1;"lines in ";FILE.NAME$
140 RETURN
150 'CHECK.FOR.EOF|
160 ERROR.CODE = ERR : ERROR.LINE = ERL
170 IF NOT(ERROR.CODE = 62) THEN 210
180 DONE.SW = 1
190 RESUME NEXT
200 GOTO 230
210 PRINT "BASIC error ";ERROR.CODE;"at";ERROR.LINE
220 STOP 'Immediately halt program
230 END
A>
This is a conventional BASIC program that can now be run using ____
BASIC or BASICA.
Page 4 111483105 Rascal Preprocessor User's Manual
To summarize our example, which demonstrated the process of
creating a Rascal program:
1. We first use a text editor to write the program. The
program contains special Rascal statements (which we'll
cover soon), is free of line numbers, has lots of blank
lines and indenting, and is easier to read and maintain
than regular BASIC.
2. We then use the Rascal preprocessor program, RASCAL.EXE,
to translate the Rascal program into one with everyday
BASIC statements in it.
3. The translated BASIC program is now run and debugged as
usual from BASIC.
PROGRAM REQUIREMENTS PROGRAM REQUIREMENTS
To preprocess Rascal programs, you need an IBM PC or XT
with:
- at least 64KB of memory,
- at least one single-sided diskette drive,
- a color or monochrome adapter, with a monitor capable of
displaying 80-character lines.
- MS DOS version 1.1 or 2.0, and
- BASIC.COM or BASICA.COM
You also need the files:
RASCAL.EXE
RAS.BAT
available on the diskette with BASIC or BASICA.
Page 5 111483105 Rascal Preprocessor User's Manual
THE RAS.BAT FILE THE RAS.BAT FILE
The file RAS.BAT has been included to make processing Rascal
source files easier. Instead of using RASCAL.EXE and completely
specifying the input and output file names, RAS.BAT gives you a
command called RAS that assumes a .RAS extension on the Rascal
program's filename and a .BAS extension on the output BASIC
filename. The format of the RAS command is simply:
A>ras {filename}
The word "filename" in { }s means you have to supply your
filename (without specifying the extension) for the command to
work properly. To preprocess the file LC.RAS, for example, we'd
use:
A>ras lc
Now that we've covered how to preprocess Rascal programs, let's
delve into how to write them.
RASCAL STATEMENTS RASCAL STATEMENTS
Your Rascal source program is composed of Rascal statements.
A Rascal statement is similar to a BASIC statement, except the
line number is missing: Rascal supplies this for you when it
builds the BASIC program from your Rascal program. If
10 PRINT "Hello, world"
is a BASIC statement, then
PRINT "Hello, world"
is the matching Rascal statement. Only the line number is
missing. You can have any number of blanks and tab characters
in your Rascal statements. In fact, this is encouraged since
this helps make your Rascal programs easier to read.
Page 6 111483105 Rascal Preprocessor User's Manual
LABELS LABELS
Without line numbers in front of statements, you need another
way to mark the places in a program where control is to go during
its execution. You can do this in Rascal with alphanumeric
labels instead of line numbers. In a BASIC program, we might
write two statements as:
960 GOTO 1030
and
1030 STOP 'End the program
In Rascal, these two statements would be written instead as:
GOTO THE.END
and
THE.END| STOP
Labels can be from 1 to 32 characters in length. Only the
characters 0-9, A-Z, a-z, and "." (period) can be in a label.
This is to keep labels from conflicting from other BASIC
keywords. The "|" (vertical bar) is used only where the label is
defined; notice that it's not there in the GOTO statement. It's
used to set the label off from the rest of the line.
Another example of labels in a Rascal program is in LC.RAS.
The statements:
ON ERROR GOTO CHECK.FOR.EOF
and
CHECK.FOR.EOF|
also demonstrate how labels are referenced (the ON GOTO
statement) and defined (the CHECK.FOR.EOF| statement) in Rascal.
The Rascal statements that can use labels are:
ON ERROR GOTO {label}
ON n GOTO {label1},{label2},...
RESTORE {label}
RESUME {label}
RETURN {label}
Page 7 111483105 Rascal Preprocessor User's Manual
PROCEDURES PROCEDURES
Rascal provides procedures to help organize your programs.
Procedures are similar to BASIC subroutines, except they are
identified by and called with an alphanumeric name. Procedures in
Rascal look like this:
PROCEDURE {procname} ____
statements making up the procedure
ENDPROC ____
(You don't have to spell out the word PROCEDURE; PROC will do, as
will ENDP for ENDPROC. In this manual, the underlines show which
part is required.) To GOSUB to a procedure you can use either:
GOSUB {procname} ____
or
DO {procname} __
with the rules for procedure names being the same as for label
names.
The other Rascal statements that can call procedures are:
ON n DO {procname1},{procname2},...
ON COM(n) DO {procname}
ON KEY(n) DO {procname}
ON PEN DO {name}
ON PLAY(n) DO {procname}
ON STRIG(n) DO {procname}
ON TIMER(n) DO {procname}
Every Rascal program requires at least one procedure, called
MAIN. Control is always given to MAIN with a GOSUB when the
program is started (see lines 10-50 of LC.BAS). So, our "Hello,
world" example needs three statements to work properly:
PROCEDURE MAIN
PRINT "Hello, world"
ENDPROC
Like white space, you should liberally use procedures in your
Rascal programs. They help break your program into mind-size
chunks for better organization. Even a single statement deserves
its own procedure if doing so will make the program easier to
read.
Page 8 111483105 Rascal Preprocessor User's Manual
IF BLOCKS IF BLOCKS
The only place in your Rascal programs where you can't freely
use a label to stand for a line number is in an IF statement.
Instead, a special form of IF is used in Rascal, called an "IF
block". It looks like this:
IF {condition} __
statements executed if {condition} is true
ELSE ____
statements executed if {condition} is false
ENDIF ____
An example of an IF block is in LC.RAS:
IF ERROR.CODE = 62
DONE.SW = 1
RESUME NEXT
ELSE
PRINT "BASIC error ";ERROR.CODE;"at";ERROR.LINE
STOP 'Immediately halt program
ENDIF
Briefly, IF the variable ERROR.CODE has the value 62 then the
statements DONE.SW = 1 and RESUME NEXT will be executed. This
will occur if we have reached the end of the file we are reading.
If ERROR.CODE is not 62, then another, more sinister BASIC error
has occurred that we don't know how to handle. The statements
after the ELSE display the error code and line number and stop
the program.
Why should you use IF blocks in a Rascal program instead of
BASIC's IF {condition} THEN {line number} statement? Because the
IF block gives you the advantage of always knowing exactly where
control begins and ends: with no GOTO statements in the IF and
ELSE parts of the block, execution beginning at the IF statement
will always resume after the ENDIF statement, regardless of what
happens in between. With BASIC's IF statement, you can picture
control splitting into two separate paths with each THEN. Pretty
soon, as patches and revisions are made, your program becomes a
mess of "spaghetti code".
If you faithfully use the IF block for your program's logic
you should seldom find the need for a GOTO statement. GOTOs
should be saved only for unusual conditions that require special
processing, such as errors.
Page 9 111483105 Rascal Preprocessor User's Manual
REPEAT AND WHILE BLOCKS REPEAT AND WHILE BLOCKS
Right now, many of your program loops in BASIC are written
using IFs and GOTOs. To help make these more structured, Rascal
provides a REPEAT block for executing a group of statements over
and over until a terminating condition is reached. It looks like
this:
REPEAT ____
statements to keep repeating
UNTIL {condition} ____
A REPEAT block is used in LC.RAS:
REPEAT
LINE INPUT #1, L$
LINE.COUNT = LINE.COUNT+1
UNTIL DONE.SW = 1
Remember that REPEAT is like any loop you might make with GOTOs
in BASIC: you need to change something at some point in the
statements you're repeating to stop the loop or you'll continue
forever.
Besides meeting the condition for termination, you can use a
BREAK statement in the REPEAT block to transfer control
immediately outside the loop. To use a BREAK statement, simply
specify
BREAK ____
Besides REPEAT, Rascal provides a WHILE loop similar to the
one already in Microsoft BASIC:
WHILE {condition} ____
statements to repeat while {condition} is true
ENDWHILE ____
When using the WHILE block, remember that the {condition} is
tested before the statements in the body of the loop are ever
executed, so it's possible to not do them at all. Also, be sure
you use ENDWHILE instead of WEND in Rascal, or RASCAL.EXE will
give you an error message. When the BASIC program is generated,
a WHILE block will not have any Microsoft WHILE statements in
it. Instead, IFs and GOTOs are used to make the loop, so the
program can be converted to computers that don't have as advanced
a version of BASIC.
You can also use BREAK to get out of a WHILE loop.
Page 10 111483105 Rascal Preprocessor User's Manual
INCLUDE FILES INCLUDE FILES
A useful technique in programming is designing a program as a
set of small, independent modules. This makes programs easier to
change, since revisions (like a changing the layout of a file)
only affect a small component (the subroutines that read or write
the file). Modular programming is hard to do with BASIC because
all the pieces of your program must be present in a single file,
with one set of line numbers. To help you develop your programs
as small modules, Rascal has an INCLUDE statement. Before
telling you what it does, here's what it looks like:
INCLUDE {filename.ext}
INCLUDE is used to bring statements into a program from a
completely separate file during preprocessing, to be part of the
program when it's translated into BASIC. The statements in the
"included" file are also Rascal statements. They can define and
reference labels, procedures, and blocks exactly as if they were
in the original source file. In fact, the INCLUDEd file can
itself have INCLUDE statements in it.
INCLUDE is an extremely useful feature of Rascal, because now
you can write frequently-used pieces of programs, such as input
routines and screen formatters, once as sets of Rascal procedures
and just INCLUDE them into each new program that you write. When
you edit these new programs you don't have to manually APPEND the
pieces, since RASCAL.EXE will automatically take care of the line
numbering for you. (But not the variables.)
MULTIPLE STATEMENTS MULTIPLE STATEMENTS
In BASIC programs, you can write several statements on a
single line by separating them with the {:} character. Since
RASCAL.EXE creates a BASIC program from the statements you give
it, the {:} character will work just as it does in BASIC, but
with an important exception: the special Rascal statements
mentioned here cannot be used in multiple lines. Instead, they ______
must have their own line whenever you use them. This restriction
may change in another version of RASCAL.EXE.
Page 11 111483105 Rascal Preprocessor User's Manual
ERROR MESSAGES ERROR MESSAGES
When RASCAL.EXE processes your program, it makes two sweeps
or "passes" across it. The first pass checks for errors. There
aren't very many that you can make, since most of your program
will be passed through, untouched except for the addition of line
numbers, to BASIC. There are, however, a few ways to produce an
error message. The possible messages that you can get are listed
below, along with an explanation of how to fix the statement that
caused them. All of these messages will begin with the name of
the file being processed (since the error might be in an INCLUDEd
file) and the offending line number.
label {name} defined previously at {file} line {n}
If this error message is displayed it means you have defined
the label {name} twice (or more...) in your program. A good
candidate for the source of this problem is an INCLUDEd file
with a duplicate of a label you are using in your program.
label {name} referenced at {file} line {n} undefined
This error message is saying that you have forgotten to
define the label {name} in your program. Possible causes of
this are forgetting an INCLUDE file (especially likely if you
see a lot of these messages) or misspelling the label.
label {name} type mismatch with {file} line {n}
This error message is displayed when you try to GOTO a
procedure name or DO a LABEL|.
{type} block not active
You used an ENDIF, ENDWHILE, or UNTIL statement in your
program without first using IF, WHILE, or REPEAT.
{type} block already begun at {file} line {n}
You tried to put two ELSE statements in one IF block. You
have probably forgotten an IF statement somewhere.
procedure {name} already begun at {file} line {n}
You cannot have two procedures started at the same time. You
must end the first procedure, {name}, with an ENDPROC
statement before you can begin your new procedure.
Page 12 111483105 Rascal Preprocessor User's Manual
procedure not begun first
This error message means that an ENDPROC statement was found
in your program when no PROCEDURE statement was active.
no WHILE or REPEAT for BREAK
This error message is displayed when you use a BREAK
statement outside a WHILE or REPEAT blocks. Remember that a
BREAK transfers control to the statement immediately after
the nearest ENDWHILE or UNTIL.
RASCAL.EXE ABORTS RASCAL.EXE ABORTS
If you specify a source or object filename that can't be read
or written to for some reason (such as the name being misspelled,
the diskette having its write-protect notch covered, etc.) the
preprocessor program will print the message:
ABORT- can't open file {filename.ext}
If this happens, you should check to make sure that the source
file can be read, that any INCLUDEd files it uses can be read,
and that the object file can be written to.
Page 13 111483105 Rascal Preprocessor User's Manual
PREPROCESSOR SPEED PREPROCESSOR SPEED
This version of RASCAL.EXE can process your programs at the
rate of 120-300 lines per minute. As you can see, this rate is
highly variable and is based on a number of factors, such as the
speed of your disk drives, the version of MS DOS you are using,
even the location of the files on the diskette. If you have
frequently-used INCLUDE files you might want to consider putting
them on a RAM disk if you aren't going to change them often. This
should improve processing time a lot.
RASCAL VS. BASIC RASCAL VS. BASIC
Once you've mastered the Rascal statements, there aren't many
reasons to continue entering and debugging BASIC programs the old
way. You'll probably find that with a little practice Rascal
programs really are easier to write and maintain. The only
reasons to modify the translated BASIC programs directly are:
1. Quick "patches" or minor changes to the BASIC program
when the Rascal source code isn't available or there
isn't time to edit it again. (Such as when you're at the
customer's office and the payroll program isn't
working.)
2. "Fine tuning" for better performance, to straighten out
Rascal's "inside out" IF statements and extra GOTOs in
programs where speed and memory size are crucial.
Page 14 111483105 Rascal Preprocessor User's Manual
STATEMENT REFERENCE STATEMENT REFERENCE
Here's a list of all the special statements available to you
in this version of RASCAL.EXE. For a complete description of how
to use them, see the individual sections in this manual.
BREAK
DO {procname}
ELSE
ENDIF
ENDPROC
ENDWHILE
IF {condition}
GOSUB {procname}
GOTO {label}
INCLUDE {d:filename.ext}
ON n DO {procname1},{procname2},...
ON COM(n) DO {procname}
ON KEY(n) DO {procname}
ON PEN DO {name}
ON PLAY(n) DO {procname}
ON STRIG(n) DO {procname}
ON TIMER(n) DO {procname}
ON n GOTO {label1},{label2},...
ON ERROR GOTO {label}
REPEAT
RESTORE {label}
RESUME {label}
RETURN {label}
UNTIL {condition}
WHILE {condition}
Page 15 111483105
